APX 20157 FORTH Turtle Graphics Plus Manual

ATARI® PROGRAM EXCHANGE

William D. Volk

FORTH TURTLE GRAPHICS PLUS

Turtle graphics for use with EXTENDED fig-FORTH

Diskette: 24K (APX-20157)

User-Written Software for ATARI Home Computers

FORTH TURTLE GRAPHICS PLUS

by

Willian Volk

Proqr3M and Manual Contents © 1982 Willian D* Uolk

Copyright notice * On receipt of this computer program and associated documentation (the
software)* the author grants you a nonexclusive license to execute the enclosed software. This
software is copyrighted* You are prohibited from reproducing, translating* or distributing
this software in any unauthorized manner*

TABLE OF CONTENTS

INTRODUCTION 1

Overview 1

Required accessories 1

Optional accessories :L

Contacting the author 1

GETTING STARTED 2

«

Loading instructions 2

DisgrsM conventions 2

THE COORDINATE SYSTEM 3

SETTING A WINDOW __ 4

TURTLE FUNCTIONS 5

MOVE 5

TURN 5

TURNTO __ 5
REN _„ 5

PENUR 5

RENDN 5

G CJ X V 5

DRAWTO __ 5

CLEAR 5

FRAMEIT 5
CENTER __ 5

BOX 5

CUBE 6

CIRCLE 6

JKSINf xtCOS,. x;TAN 6

DUEMOVE 6

GRx 6

SCREEN DESCRIPTIONS __ 7

SAMPLE APPLICATIONS 8

Typical LOGO function S

Using FORTH TURTLE GRAPHICS PLUS WITH OTHER FORTHS

AND OTHER COMPUTERS 3

S a MP 1 e FORT H t u r 1 1 e c o m n a n ti s 3

S a m p 1 e g r a p h i c s n o d e 8 s c r e e ri ti u rt p s 8

SUGGESTED REFERENCES __. 11

SCREEN LISTINGS __ 12

XNTRODUCTXON

OVERVIEW

FORTH TURTLE GRAPHICS PLUS is a package of FORTH "words" (functions) that adds the
standard turtle graphics of languages like ATARI PILOT and LOGO to EXTENDED fig-FORTH,
available through AFX* Implemented in integer math* the package also supports a
normalized coordinate system, the ability to create windows with clipped lines on any
part of the screen display without having to modify a program, the twelve graphics modes
available with the new GTIA chip, and the TRIG functions *SXN» *COS f and *TAN for use in
FORTH programs* Also included is a graphics mode 8 screen dump utility for Epson printers
with GRAFTRAX* Yet with all these features, FORTH TURTLE GRAPHICS PLUS compiles to only
2K of memory!

REQUIRED ACCESSORIES

24K RAM (more for some graphics modes)
Extended fig-Forth (AFX-20029)
ATARI 810 Disk Drive

OPTIONAL ACCESSORIES

EPSON MX-80 or 100 Printer with GRAFTRAX

CONTACTING THE AUTHOR

■

This package is an evolving entity* If you have suggestions or improvements, please write
to the author at J

Box 2 0 53 Bab cock House
Durham, NH 03824

THE COORDINATE SYSTEM

While you're using FORTH TURTLE GRAPHICS PLUS, the coordinate system is fixed and
independent of the ATARI Computer's graphic coordinates* It is centered on 0*0 and
extends to +/-1000 along both the X and Y axes* Figure 1 depicts the range along both
axes*

+ 1000

*

-10 0 0 < + > +10 0 0

♦

*

♦

■

V

-1000

Figure 1 Range along X and Y axes

The two screen modes best used with FORTH TURTLE GRAPHICS PLUS are BASIC modes 7 and S«
These modes are accessed by the functions GRS and GR7, which set the window to the entire
graphic display* The GTIA modes are on screen 8, which includes the functions GR? and

GR11* To use other modes* use the GR* function ( mode )♦ as described in the EXTENDED

fig-Forth documentation* and set an appropriate window*

TURTLE FUNCTIONS

MOVE ( x

Move in the current direction x units.
TURN (x )

Turn x degrees to the right*
TT7KKTO ( x )

Turn to a direction of x degrees*
PEN ( x )

Select pen color x and place the pen down* The color corresponds to the COLOR
command in ATARI BASIC*

PENUP( )

Lift the pen up*

PENDN (

)

Place the pen down.
GOXT ( x y )

Go to the coordinate x, y with the pen up.

DRAWTO ( x y

)

Go to the

linate x, y with the pen down.

CLEAR < n )

Fill the window with color n.
FRAMEIT ( n )

Draw a box around the window in color n.

CENTER ( )

The same as a 0 0 GOXY command*

BOX ( n )

Draw a box of dimension n*

SCREEN DESCRIPTIONS

Screen 1

Contains the code to create the trig table used by *SIN* *COS* and *TAN* This table
is located by the variable TRIGTAE*

Screen 2

The recursion function RECURSE is defined on line 0. This allows a FORTH word to
call itself* Recursion is used by the function ANGSET, which converts any angle to
an angle within 0-33? degrees* The trig functions are defined on this screen* The
trig functions *$Dl# *COS, and *TAN are implemented by doing a look-up on TRIGTAB*

Screen 3

The variables used by FORTH TURTLE GRAPHICS PLUS are defined here. Some functions
are also defined* The coordinate size* +/- 1000, is set on line 15*

Screen 4

Some of the clipping functions, the variables used by the clipping function* and the
transformation to the window are defined here*

Screen 5

This screen contains the bulk of the clipping function ♦ which clips lines to the +/-
1000 window* It is based on the FORTRAN clipping program in A Practical
Introduction to Computer Graphics * This results in a larger FORTH function than
is normally desirable*

Screen 6

The remaining turtle functions are defined here* Some examples of turtle functions
(BOX* CUBE* and CIRCLE) are also defined*

Screen 7

The CLEAR and CENTER functions are defined here*
Screen 8

The GTIA extensions are defined* along with the demonstrations GSQUIRAL* BOXES,
SPIRAL* DEMO 1 1 and BEM02* All demonstrations except DEM02 have a stack diagram (
)♦ specifying the number of iterations* (DEM02 does not affect the stack*)

Screen 9

This screen defines GRDUMP ( )♦ which sends a graphics mode 3 screen dump to an

Epson printer with GRAFTRAX* You must execute a PON command before dumping* The
data is echoed on the bottom of the screen J the data may include the bell character*

9 LOAD

to load in the screen containing the graphics mode 3 screen dump function* Then to dump
the circle command, type

GR8 INIT 100 CIRCLE PON GRDUMP POFF

The figure looks like this:

To dump the BOX command, type

GRS INIT 50 0 BOX PON GRDUMP POFF
The figure looks like thisJ

To dump the CUBE command, type

GRS INIT '!0 0 CUE:E PON GRDUMP POFF

—

SUGGESTED REFERENCES

i. mind-storms: Child

-uters, and Powerful Ideas, Seymour Papert.

A good introduction to turtle graphics and procedural programming,

2. Starting FORTH, Leo Brodie, Prentice-Hall, 1981.

The best introduction to FORTH programming,

3. A Practical Introduction to Computer Graphics, Ian O. Angell.

Good discussion of clipping functions. Contains FORTRAN listings of programs.

4, Fundamentals of Interactive Computer Graphics, J *D* Foley & A* Van Dam*

Excellent graphics text. Good explanation of windowing and its uses*

Additional documentation on fig -FORTH is available from the FORTH Interest Group, P.O.
Box 1105, San Carlos, CA 94070*

SCR # 1

0

0 VARIABLE TRIGTAB 571

f 1143

1714 ,

2

xi. S 5 ♦

1

3425 ,

3993 f

4

56 0 f 5

1

£, sj f \J O O 7

t

j> to %J JL.

, 6812

t

2

7370 ,

7927 f

8

480 , 90

31 , 95

80

, 10125

, 10667 ,

3

11206

y

11742

-/

12274

t

12803

13327

t

13847

14364

t

14875

t

15333

t

15385

16383

t

16876

t

17363

17346

.+

1 OO *7 O
.L v„< o u

18794

t

19259

t

19719

f

6

20173

20620

*

21062

t

21497

t

21925

22347

t

7

22761

t

23169

23570

t

23964

t

24350

f

24729

t

8

25100

t

25464

t

25820

t

26168

t

26509

*

26841

f

9

27165

f

27480

t

27787

t

28036

t

28377

t

28658

*

10

28931

t

29195

t

29450

29696

29934

*

30162

t

11

30381

30590

f

30790

t

30981

f

31163

t

31335

t

.1 4m

31497

31650

♦

3 1 7Q^

31927

t

32050

t

32164

t

13

3 jl. 2 6 9

*

3 2 3 6 3

32448

t

32522

32587

*

32642

f

14

32687

t

32722

t

32747

t

32762

t

32767

t

15 — >

0 5 RECURSE LATEST RFA CFA , \ IMMEDIATE ( RECURSION )

1 32767 CONSTANT MAXINT ( LARGEST INTERGER )

2 : GETRIG 2 * TRIGTAB + 8 } < RETURNS TABLE ELEMENT N )

3 { ANGSET DUR 359 > IF 36 0 - RECURSE ELSE DUP

4 0 < IF 360 + RECURSE ENDIF ENDIF X < GET ANGLE 0-359 )

5 : SGNSIN ANGSET 180 > IF MINUS ENDIF J ( GIVE SIGN TO VALUE )

6 : SGNCOS 90 + SGNSIN X

7 t INDEXSIN DUR 180 > IF 180 - ENDIF DUP 90 > IF 13 0 SWAP -

8 ENDIF t ( GET THE INDEX OF THE SIN FUNCTION )

9 I INDEXCOS INDEXSIN 90 SWAP - X ( GET COS OFFSET )

10 t GETSIN ANGSET DUP INDEXSIN GETRIG SWAP SGNSIN X

11 t GETCOS ANGSET DUP INDEXCOS GETRIG SWAP SGNCOS X ( VALUES )

12 X *SIN GETSIN MAXINT */ X ( N ANG N*SIN )

13 t *COS GETCOS MAXINT */. }.<' H ANG N*COS )

14 t *TAN DUP GETSIN SWAP GETCOS */ } ( N ANG N*TAN )

15 — >

SCR * 3

0 ( TURTLE GRAPHICS WILLIAM VOLK 3/29/82 )

1 0 VARIABLE TURTANG ( ANGLE OF MOTION )

2 : TURN TURTANG @ SWAP - ANGSET TURTANG ! J ( TURN TURTLE )

3 t TURNTO ANGSET TURTANG ! X

4 0 VARIABLE TURTCOL. ( COLOR OF PEN )

5 0 VARIABLE LCORX 0 VARIABLE LCORY 0 VARIABLE RCORX

6 0 VARIABLE RCORY 0 VARIABLE XI 0 VARIABLE Yl 0 VARIABLE X2

7 0 VARIABLE Y2 0 VARIABLE PEN DOWN ( 0 PEN IS UP, 1 DOWN )

8 t PEN TURTCOL ! 1 P END OWN ! J- < SET COLOR PEN IS DOWN )

9 5 P END OWN? PENDOWN @ \ < LOGICAL TEST OF PEN )

10 : PENUP 0 PENDOWN ! X ( LIFT THE PEN UP )

11 J WINDOW RCORY ! RCORX 1 LCORY ! LCORX ! X ( SET SCREEN )

12 { GR7 XGR 7 GR . 0 0 159 79 WINDOW X

13 J GR8 XGR 8 GR, 0 0 319 159 WINDOW X

14 i PENDN 1 PENDOWN ! } ( PLACE THE PEN DOWN )

15 10 0 0 CONSTANT PICSIZE — >

SCR # 7

0 ( TURTLE GRAPHIC FUNCTIONS )

1

CLEAR RCORY 0 1 + LCORY 0 DO

2 DUP LCORX 0 I PLOT DUP RCORX 0

3 LOOP DROP J

4 : CENTER 0 0 GOXY
5
6

( CLEAR WINDOW
I DRAW

7
8
?
10
11

.1. dmi

13
14
15

SCR
0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

* 8

♦

<■

♦

♦

+

♦

GITA DEMOS )
GR? XGR 9 GR ♦ 0
GR11 XGR 11 GR.

♦

*

0 79 191 WINDOW CENTER
0 0 79 191 WINDOW CENTER
GSQUIRAL 1 DO I PEN I II) i MOVE 123 TURN LOOP
BOXES 1 DO I PEN 110* BOX LOOP \
SPIRAL 1 DO I PEN I MOVE 3 0 TURN LOOP I
DEMOl 1 DO I PEN 110* BOX 10 TURN LOOP t
DEM02 12 1 DO I 1 - CLEAR I PEN 70 0 CUBE LOOP

♦

♦

SCR * 9

0 ( PRINT DUMP GR8 )

1 J ROWDUMP -1 160 DO DUP 88(? + I40* + G? EMIT -1 +LOOP DROP

2 t SETDUMP " 27 EMIT 75 EMIT 160 EMIT J

3 t GRDUMP 27 EMIT 65 EMIT 3 EMIT CR 4 0 0 DO SETDUMP I ROWDUMP

4 CR LOOP ?

5 : DEMO CENTER 1 DO I 20 * BOX 10 TURN LOOP ; ( GRAPHICS )
6
7
8
9

10
11

LIMITED WARRANTY ON MEDIA AND HARDWARE ACCESSORIES*

We, Atari, Inc*, guarantee to you* the original retail purchaser, that the medium on
which the APX program is recorded and any hardware accessories sold by APX are free from
defects for thirty days from the date of purchase* Any applicable implied warranties,
including warranties of merchantability and fitness for a particular purpose, are also
limited to thirty days from the date of purchase* Some states don't allow limitations on
a warranty's period, so this limitation might not apply to you* If you discover such a
defect within the thirty-day period, call APX for a Return Authorization Number, and then
return the product along with proof of purchase date to APX* We will repair or replace
the product at our option*

You void this warranty if the APX product: (1) has been misused or shows signs of
excessive wear? (2) has been damaged by use with non-ATARI products} or (3) has been
serviced or modified by anyone other than an Authorized ATARI Service Center* Incidental
and consequential damages are not covered by this warranty or by any implied warranty*
Some states don't allow exclusion of incidental or consequential damages, so this
exclusion might not apply to you*

DISCLAIMER OF WARRANTY AND LIABILITY ON COMPUTER PROGRAMS*

Most APX programs have been written by people not employed by Atari, Inc* The programs we
select for APX offer something of value that we want to make available to ATARI Home
Computer owners* To offer these programs to the widest number of people economically, we
don't put APX products through rigorous testing* Therefore, APX produts are sold "as is",
and we do not guarantee them in any way* In particular, we make no warranty, express or
implied, including warranties of merchantability and fitness for a particular purpose* We
are not liable for any losses or damages of any kind that result from use of an APX
product*

ATARI F>^Q<3r^A3>l

EXCHANGE

REVIEW FORM

We're interested in your experiences with APX programs and documentation , both favorable and
unfavorable. Many software authors are willing and eager to improve their programs if they know
what users want* And* of course* we want to know about any bugs that slipped by us* so that the
software author can fix them* We also want to know whether our documentation is meeting your needs
You are our best source for suggesting improvements! Please help us by taking a moment to fill in
this review sheet* Fold the sheet in thirds and seal it so that the address on the bottom of the
back becomes the envelope front* Thank you for helping us!

I. Name and AFX number of program

2* If you have problems using the program* please describe them here.

3* What do you especially like about this program?

—

1 1

4* What do you think the program's weaknesses are?

*

5* How C2

m the catalog descr

iption be more accu

rate and/or comprehensive?

6* On a scale of 1 to 10* 1 being "poor" and 10 being " excellent", please rate the following
aspects of this program?

Easy to use

User-oriented (e*g** menus* prompts, clear language)

Enjoyable

Self-instructive

Useful (non-game software)

Imaginative graphics and sound

7* Describe any technical errors you found in the user instructions (please give page numDers)*